Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tclx / TclX.man < prev

Wrap

Text File | 1992-04-07 | 50.9 KB | 1,255 lines

TclX UNKNOWN MANUAL SECTION TclX NNAAMMEE TclX - Extended Tcl - Extended command set for Tcl 6.1. IINNTTRROODDUUCCTTIIOONN This man page contains the documentation for all of the extensions that are added to Tcl 6.1 by Extended Tcl. These extensions provide their capabilities by adding new commands to Tcl whitout changing the syntax of standard Tcl. Extended Tcl is a superset of standard Tcl and is built with the standard Tcl sources. The command descriptions are separated into several sections: o General Commands o Unix Access Commands o File I/O Commands o File Scanning Commands o Math Commands o List Manipulation Commands o Keyed Lists o String and Character Manipulation Commands GGEENNEERRAALL CCOOMMMMAANNDDSS A set of general useful Tcl commands. Includes interactive inputting of commands, a facility for tracing execution and a looping command. ccoommmmaannddlloooopp [[_p_r_o_m_p_t] [_p_r_o_m_p_t_2] Create an interactive command loop for the current TCL interpreter. This command receives commands from stdin and executes them. This command is useful for non- interactive TCL scripts that want to enter an interac- tive mode. _P_r_o_m_p_t is a command string to set the top level prompt hook to to, the contents of which is executed to generate the main prompt. _P_r_o_m_p_t_2 is a command string to set the down level prompt to, which is generates the prompt command for continuation input. When the command ter- minates, the variables for the prompt hooks will be set to their old value. If these arguments are not speci- fied, the prompt hooks use their current value. Prompt hooks are TCL code that return as their result the prompt to output. The result of the last command exe- cuted in the command string (which may be a rreettuurrnn) will be outputted as the prompt. Tcl 1 TclX UNKNOWN MANUAL SECTION TclX ccmmddttrraaccee _l_e_v_e_l|oonn [nnooeevvaall] [nnoottrruunnccaattee] [fflluusshh] [_f_i_l_e_h_a_n_d_l_e] Print a trace statement for all commands executed at depth of _l_e_v_e_l or below (1 is the top level). If oonn is specified, all commands at any level are traced. If nnooeevvaall is specified, arguments are printed unevaluated -- if it is not specified, the arguments are printed after evaluation. If the command line is longer than 60 characters, it is truncated to 60 and a "..." is post- pended to indicate that there was more. If nnooeevvaall wasn't specified, the arguments are printed after evaluation. In this case, each argument is truncated to 40 characters (with "..." postpended if the argument was longer than 40 characters) and printed. If an evaluated argument contains a space, the entire argu- ment will be enclosed inside of braces (`{}') to allow the reader to visually separate the arguments from each other. If nnoottrruunnccaattee is specified, then the truncation of commands and evaluated arguments will be disabled. If fflluusshh is specified, then the output buffer will be flushed after each line is printed. This is useful when tracing code that cause an application to abort, making it easy to narrow the problem down to the com- mand that caused the abort. If _f_i_l_e_h_a_n_d_l_e is specified, then the trace output will be written to the file. ccmmddttrraaccee ooffff Turn off all tracing. ccmmddttrraaccee ddeepptthh Returns the current maximum trace level, or zero if trace is disabled. eecchhoo _s_t_r_1 [_s_t_r_2..] Print the strings to stdout followed by a newline. iinnffooxx _o_p_t_i_o_n Return information about extended Tcl or the current application. The following iinnffooxx command options are available. vveerrssiioonn Return the version number of Extended Tcl. The version number for extended Tcl is generated by combining the base version of the standard Tcl code with a letter indicating the version of Extended Tcl being used. This is the documenta- tion for version ttccll66..11aa. ppaattcchhlleevveell Return the patchlevel for Extended Tcl. aappppnnaammee Tcl 2 TclX UNKNOWN MANUAL SECTION TclX Return the symbolic application name of the current application linked with the Extended Tcl library. The C variable ttccllAAppppNNaammee must be set by the application to return an application specific value for this variable. aapppplloonnggnnaammee Return a natural language name for the current application. The C variable ttccllLLoonnggAAppppNNaammee must be set by the application to return an application specific value for this variable. aappppvveerrssiioonn Return the version number for the current applica- tion. The C variable ttccllAAppppVVeerrssiioonn must be set by the application to return an application specific value for this variable. lloooopp _v_a_r _f_i_r_s_t _l_a_s_t [_i_n_c_r_e_m_e_n_t] _b_o_d_y LLoooopp is a looping command, similar in behavior to the Tcl ffoorr statement, except that the lloooopp statement achieves substantially higher performance and is easier to code when the beginning and ending values of a loop are known and the loop variable is to be incremented by a known, fixed amount every time through. The _v_a_r argument is the name of a Tcl variable that will contain the loop index. The loop index is first set to the value specified by _f_i_r_s_t. The Tcl inter- preter is invoked upon _b_o_d_y zero or more times, where _v_a_r is incremented by _i_n_c_r_e_m_e_n_t every time through the loop, or by one if _i_n_c_r_e_m_e_n_t is not specified. _I_n_c_r_e_- _m_e_n_t can be negative in which case the loop will count downwards. When _v_a_r reaches _l_a_s_t, the loop terminates without a subsequent execution of _b_o_d_y. For instance, if the original lloooopp parameters would cause lloooopp to terminate, say _f_i_r_s_t was one, _l_a_s_t was zero and _i_n_c_r_e_m_e_n_t was not specified or was non-negative, _b_o_d_y is not executed at all and lloooopp returns. If a ccoonnttiinnuuee command is invoked within _b_o_d_y then any remaining commands in the current execution of _b_o_d_y are skipped, as in the ffoorr command. If a bbrreeaakk command is invoked within _b_o_d_y then the lloooopp command will return immediately. LLoooopp returns an empty string. UUNNIIXX AACCCCEESSSS CCOOMMMMAANNDDSS These commands provide access to many basic Unix facilities, including process handling, data and time, signal handling, linking and unlinking files, changing file attributes, Tcl 3 TclX UNKNOWN MANUAL SECTION TclX process and user attributes and the executing commands via the shell. aallaarrmm _s_e_c_o_n_d_s Instructs the system to send a SIGALRM signal in the specified number of seconds. If _s_e_c_o_n_d_s is 0, any pre- vious alarm request is canceled. Only one alarm at a time may be active, the command returns the number of seconds left in the previous alarm. cchhggrrpp _g_r_o_u_p _f_i_l_e_l_i_s_t Set group of each file in the list _f_i_l_e_l_i_s_t to _g_r_o_u_p, which is a group name or numeric group id. cchhmmoodd [[--ii] _m_o_d_e _f_i_l_e_l_i_s_t Set permissions of each of the files in the list _f_i_l_e_l_- _i_s_t to _m_o_d_e, which is an absolute numeric mode or sym- bolic permissions as in the cchhmmoodd((CC)) UNIX command. Normally absolute modes are assumed to be specified in octal. However Tcl stores numbers internally as integers. The --ii option causes an absolute mode to be treated as a standard Tcl integer (decimal unless pre- fixed by "0" of "0x"). cchhoowwnn _o_w_n_e_r|{_o_w_n_e_r _g_r_o_u_p} _f_i_l_e_l_i_s_t Set owner of each file in the list _f_i_l_e_l_i_s_t to _o_w_n_e_r, which is a owner name or numeric owner id. If the first parameter is a list, then the owner is set to the first element of the list and the group is set to the second element of the list. _G_r_o_u_p is a group name or numeric group id. If _g_r_o_u_p is {}, then the file group will be set to the group for the associated the speci- fied user. eexxeeccvvpp _p_r_o_g [_a_r_g_1..._a_r_g_N] Do an execvp, replacing the current program with _p_r_o_g and passing the arguments _a_r_g_1..._a_r_g_N. ffmmttcclloocckk _c_l_o_c_k_v_a_l [_f_o_r_m_a_t] [GGMMTT||{{}}] Convert a value returned by ggeettcclloocckk or ffiillee to human readable form. The _f_o_r_m_a_t argument is a string that describes how to format the date and time. Field descriptors consist of a ``%'' followed by a field descriptor. All other characters are copied into the result. The available field descriptors are: %% - Insert a %. %a - Abbreviated weekday name. %A - Full weekday name %b - Abbreviated month name. %B - Full month name. %d - Day of month (01 - 31). Tcl 4 TclX UNKNOWN MANUAL SECTION TclX %D - Date as %m/%d/%y. %e - Day of month (1-31), no leading zeros. %h - Abbreviated month name. %H - Hour (00 - 23). %I - Hour (00 - 12). %j - Day number of year (001 - 366). %m - Month number (01 - 12). %M - Minute (00 - 59). %n - Insert a new line. %p - AM or PM. %r - Time as %I:%M:%S %p. %R - Time as %H:%M. %S - Seconds (00 - 59). %t - Insert a tab. %T - Time as %H:%M:%S. %U - Week number of year (01 - 52), Sunday is the first day of the week. %w - Weekday number (Sunday = 0). %W - Week number of year (01 - 52), Monday is the first day of the week. %x - Local specific date format. %X - Local specific time format. %y - Year within century (00 - 99). %Y - Year as ccyy (e.g. 1990) %Z - Time zone name. If format is not specified, "%a %b %d %H:%M:%S %Z %Y" is used. If GGMMTT is specified, the time will be for- mated as Greenwich Mean Time. If the argument is not specified or is empty, then the local timezone will be used as defined by the timezone environment variable. ffoorrkk Fork the current TCL process. Fork returns zero to the child process and the process number of the child to the parent process. If an eexxeeccvvpp is not going to be performed before the forked process does output, then a fflluusshh should be issued against ssttddoouutt, ssttddeerrrr and any other open output file before doing the ffoorrkk. Other- wise, output from the parent process pending in the buffers will also be outputted by the child process. ggeettcclloocckk Return the current date and time as a system dependent integer value. The unit of the value is seconds, allowing it to be used for relative time calculations and so forth. iidd ooppttiioonnss This command provides a means of getting, setting and converting user, group and process ids. The following versions of the iidd command are available: Tcl 5 TclX UNKNOWN MANUAL SECTION TclX iidd uusseerr [_n_a_m_e] iidd uusseerriidd [_u_i_d] Set the real and effective user ID to _n_a_m_e or _u_i_d, if the name (or uid) is valid and permissions allow it. If the name (or uid) is not specified, the current name (or uid) is returned. iidd ccoonnvveerrtt uusseerriidd _u_i_d iidd ccoonnvveerrtt uusseerr _n_a_m_e Convert a user ID number to a user name, or vice versa. iidd ggrroouupp [_n_a_m_e] iidd ggrroouuppiidd [_g_i_d] Set the real and effective group ID to _n_a_m_e or _g_i_d, if the name (or gid) is valid and permissions allow it. If the group name (or gid) is not specified, the current group name (or gid) is returned. iidd ccoonnvveerrtt ggrroouuppiidd _g_i_d iidd ccoonnvveerrtt ggrroouupp _n_a_m_e Convert a group ID number to a group name, or vice versa. iidd eeffffeeccttiivvee uusseerr iidd eeffffeeccttiivvee uusseerriidd Return the effective user name, or effective user ID number, respectively. iidd eeffffeeccttiivvee ggrroouupp iidd eeffffeeccttiivvee ggrroouuppiidd Return the effective group name, or effective group ID number, respectively. iidd pprroocceessss Return the process ID of the current process. iidd pprroocceessss ppaarreenntt Return the process ID of the parent of the current process. iidd pprroocceessss ggrroouupp Return the process group ID of the current pro- cess. Tcl 6 TclX UNKNOWN MANUAL SECTION TclX iidd pprroocceessss ggrroouupp sseett Set the process group ID of the current process to its process ID. kkiillll [[_s_i_g_n_a_l] _p_r_o_c_e_s_s_l_i_s_t Send a signal to the each process in the list _p_r_o_- _c_e_s_s_l_i_s_t, if permitted. _S_i_g_n_a_l, if present, is the signal number or the symbolic name of the signal, see the signal system call manual page. The leading "SIG" is optional when the signal is specified by its sym- bolic name. The default for _s_i_g_n_o is 15, SIGTERM. lliinnkk _s_r_c_p_a_t_h _d_e_s_t_p_a_t_h Create a directory entry, _d_e_s_t_p_a_t_h, linking it to the existing file, _s_r_c_p_a_t_h. mmkkddiirr [[--ppaatthh]] _d_i_r_L_i_s_t Create each of the directories in the list _d_i_r_L_i_s_t. The mode on the new directories is 777, modified by the umask. If --ppaatthh is specified, then any non-existent parent directories in the specified path are also created. rrmmddiirr _d_i_r_L_i_s_t Remove each of the directories in the list _d_i_r_L_i_s_t. ssiiggnnaall _a_c_t_i_o_n _s_i_g_l_i_s_t [_c_o_m_m_a_n_d] Specify the action to take when a Unix signal occurs. _S_i_g_l_i_s_t is a list of either the symbolic or numeric Unix signal (the SIG prefix is optional). _A_c_t_i_o_n is one of the following actions to be performed on receipt of the signal. ddeeffaauulltt - Terminate the process iiggnnoorree - Ignore the signal. eerrrroorr - Generate a catchable Tcl error. It will be as if the command that was running returned an error. The error code will be in the form: {UUNNIIXX SSIIGG _s_i_g_n_a_m_e} For the death of child signal, _s_i_g_n_a_m_e will always be SIGCHLD, rather than SIGCLD, to allow writting protable code. ttrraapp - When the signal occures, execute _c_o_m_m_a_n_d and continue execution if an error is not returned by _c_o_m_- _m_a_n_d. If will be executed in the global context and the symbolic signal name (e.g. SIGINT) will be supplied in a global variable ssiiggnnaallRReecciieevveedd. If an error is Tcl 7 TclX UNKNOWN MANUAL SECTION TclX returned, then follow the standard Tcl error mechanism. Often _c_o_m_m_a_n_d will just do an eexxiitt. ggeett - Retrieve the current settings of the specified signals. A list will be returned with each element containing one of `ddeeffaauulltt', `iiggnnoorree', `eerrrroorr' or `ttrraapp' corresponding to each signal in _s_i_g_l_i_s_t. For all signals except SSIIGGCCLLDD, the signal action will remain enabled after the specified signal has occured. For SSIIGGCCLLDD (also known as SSIIGGCCHHLLDD), the signal will not be automatically reenable. A wait must be performed before issuing another ssiiggnnaall command. Signals are not processed until after the completion of the Tcl command that is executing when the signal is recieved. sslleeeepp _s_e_c_o_n_d_s Sleep the TCL process for _s_e_c_o_n_d_s. ssyysstteemm _c_o_m_m_a_n_d Executes _c_o_m_m_a_n_d via the system(3) call. Differs from eexxeecc because ssyysstteemm doesn't return stdout as the result or the command and ssyysstteemm goes through the shell to provide wildcard expansion, redirection, etc, as is normal from a sshh command line. Returns the exit code of the command. ttiimmeess Return a list containing the process and child execu- tion times in the form: _u_t_i_m_e _s_t_i_m_e _c_u_t_i_m_e _c_s_t_i_m_e See times system call manual page. The values are in milliseconds. uummaasskk [[_o_c_t_a_l_m_a_s_k] Sets file-creation mode mask to the octal value of _o_c_t_a_l_m_a_s_k. If _o_c_t_a_l_m_a_s_k is omitted, the current mask is returned. uunnlliinnkk _f_i_l_e_l_i_s_t Delete (unlink) the files whose names are in the list _f_i_l_e_l_i_s_t. wwaaiitt _p_r_o_c_l_i_s_t Waits for an any of the immediate child processes specified in the list _p_r_o_c_l_i_s_t to terminate or a signal to be received. WWaaiitt returns a list of three elements: The first element is process id of the terminating pro- cess. If the process exited normally, the second ele- ment is `EXIT', followed by the error code. If the process terminated because of a signal, the second ele- ment is `SIG', followed by the signal name. If the Tcl 8 TclX UNKNOWN MANUAL SECTION TclX process is currently stopped, the second element is `STOP', followed by the signal name. FFIILLEE II//OO CCOOMMMMAANNDDSS The commands extend the stdio-style file I/O capabilities present in Tcl 6.1. These extensions include searching ASCII-sorted data files, copying files, duplicating file descriptors, control of file access options, retrieving open file status, and creating pipes with the ppiippee system call. A interface to the sseelleecctt system call is also available on Unix systems that support it. It should be noted that Tcl file I/O is implemented on top of the stdio library. By default, the file is buffered, when communicating to a process through a pipe, a fflluusshh com- mand should be issued to force the data out. Alternatively, the ffccnnttll command may be used to set the buffering mode to line buffered or unbuffered. bbsseeaarrcchh _f_i_l_e_h_a_n_d_l_e _k_e_y [_r_e_t_v_a_r] [_c_o_m_p_a_r_e__p_r_o_c] Search an opened sorted data file, _f_i_l_e_h_a_n_d_l_e, for a line matching _k_e_y. If _r_e_t_v_a_r is specified, then the line from the file is returned in _r_e_t_v_a_r and the com- mand returns 11 if _k_e_y was found, and 00 if it was not found. If _r_e_t_v_a_r is not specified or is a null name, then the command returns the line that was found, or an empty string if _k_e_y is not found. By default, the key is matched against the first white-space seperated field in each line. The field is treated as an ASCII string. If _c_o_m_p_a_r_e__p_r_o_c is speci- fied, then it is the name of a Tcl procedure to evalu- ate against each line read from the file. This _c_o_m_p_a_r_e__p_r_o_c takes two arguments, the key and a line extracted from the file. The compare routine should return a number less than zero if the key is less than the line, zero if the key matches the line or greater than zero if the key is greater than the line. The file must be sorted in assending order by whatever cri- teria _c_o_m_p_a_r_e__p_r_o_c uses to compare the key with the line. ccooppyyffiillee _h_a_n_d_l_e_1 _h_a_n_d_l_e_2 Copies the rest of file specified by _h_a_n_d_l_e_1 from its current position to the file specified by _h_a_n_d_l_e_2. dduupp _f_i_l_e_h_a_n_d_l_e [_s_t_d_h_a_n_d_l_e] Duplicate an open file. A file handle is created that addresses the same file as _f_i_l_e_h_a_n_d_l_e. A special case is allowed for dup-ing files to stdin, stdout or stderr. If _s_t_d_h_a_n_d_l_e is specified, then it Tcl 9 TclX UNKNOWN MANUAL SECTION TclX must be one of the standard handles to dup _f_i_l_e_h_a_n_d_l_e to. proc ChildProcess {cmd inPipe outPipe} { if {[set childPid [fork]] == 0} { close stdin dup $inPipe stdin close $inPipe close stdout dup $outPipe stdout close $outPipe execvp $cmd # will never make it here... } return $childPid } ffccnnttll _h_a_n_d_l_e [_a_t_t_r_i_b_u_t_e _v_a_l_u_e] This command either returns a list of various boolean attributes controlling access to a file or set or clears one of the boolean attributes. If _a_t_t_r_i_b_u_t_e and _v_a_l_u_e are not specified, then the list of the attri- butes that are set are return. If an attribute is not set, then it will not be included in the list. The following attributes maybe returned: RRDDOONNLLYY - The file is opened for reading only. WWRROONNLLYY - The file is opened for writing only. RRDDWWRR - The file is opened for reading and writing. AAPPPPEENNDD - The file is opened for append only writes. All writes will be forced to the end of the file. NNDDEELLAAYY - The file is to be accessed with non-blocking I/O. See the rreeaadd system call for a description of how it affects the behaviour of file reads CCLLEEXXEECC - Close the file on an process exec. If the eexxeeccvvpp command or some other mechanism causes the pro- cess to exec, the file will be closed. NNOOBBUUFF - The file is not buffered. If set, then there no stdio buffering for the file. LLIINNEEBBUUFF - Output the file will be line buffered. The buffer will be flushed when a newline is written, when the buffer is full, or when input is requested. Tcl 10 TclX UNKNOWN MANUAL SECTION TclX The AAPPPPEENNDD, NNDDEELLAAYY, and CCLLEEXXEECC attributes may be set or cleared by specifying the attribute name and a value 11 to set the attribute and 00 to clear it. The NNOOBBUUFF and LLIINNEEBBUUFF attributes may only be set (a value of 11) and only one of the options may be set. Once set, they may not be cleared. Thees option should be set before any I/O operations have been done on the file. ffssttaatt _h_a_n_d_l_e [_a_r_r_a_y_v_a_r] Obtain the status of an open file. This differs from the ffiillee ssttaatt command in that it takes a file handle rather than a file name. If _a_r_r_a_y_v_a_r is specified, the status information is returned in the following ele- ments of this array variable: aattiimmee, ccttiimmee, ddeevv, ggiidd, iinnoo, mmooddee, mmttiimmee, nnlliinnkk, ssiizzee, uuiidd. Each element is a decimal string with the value of the corresponding field from the ssttaatt return structure; see the manual entry for ssttaatt for details on the meanings of the values. If _a_r_r_a_y_v_a_r is not specified, then the infor- mation is returned as a keyed list. Each element of the list is itself a list with the status value name paired with its value, in alphabetical order. For example: {atime 683617279} {ctime 683617310} {dev 298} {gid 50} {ino 6317} {mode 33152} {mtime 683617310} {nlink 1} {size 924} {uid 200} ppiippee [[_h_a_n_d_l_e__v_a_r__r _h_a_n_d_l_e__v_a_r__w] Create a pipe (see the pipe system call manual page). If _h_a_n_d_l_e__v_a_r__r and _h_a_n_d_l_e__v_a_r__r are specified, then variable _h_a_n_d_l_e__v_a_r__r will contain the handle opened for reading and _h_a_n_d_l_e__v_a_r__w will contain the handle opened for writing. If the handle variables are not specified, then a list containing the read followed by the write handle is returned as the result of the com- mand. sseelleecctt _r_e_a_d_h_a_n_d_l_e_s [_w_r_i_t_e_h_a_n_d_l_e_s] [_e_x_c_e_p_t_h_a_n_d_l_e_s] [_t_i_m_e_o_u_t] This command allows polling or blocking on multiple files being ready for for reading, are ready for writ- ing, or have an exceptional condition pending. _r_e_a_d_h_a_n_d_l_e_s, _w_r_i_t_e_h_a_n_d_l_e_s, _e_x_c_e_p_t_h_a_n_d_l_e_s are each lists of file handles (as returned from ooppeenn) to query. An empty list ({}) may be specified if a category is not used. The _r_e_a_d_h_a_n_d_l_e_s files are checked to set if data is available for reading. The _w_r_i_t_e_h_a_n_d_l_e_s are checked if Tcl 11 TclX UNKNOWN MANUAL SECTION TclX they are clear for writing The _e_x_c_e_p_t_h_a_n_d_l_e_s are checked to see if an exceptional condition has occured. The write and exception checking is most useful on dev- ices, however, the read checking is also very valuable when communicating with multiple processes through pipes. _T_i_m_e_o_u_t is a floating point timeout number of seconds. If an empty list is supplied (or the parameter is omit- ted), then no timeout is set. If the value is zero, then the sseelleecctt command functions as a poll of the files. If the _t_i_m_e_o_u_t period expires with none of the files becomming ready, then the command returns an empty list. Otherwise the command returns a list of three elements, each of those elements is a list of the file handles that are ready in the read, write and exception classes. If none are ready in a class, then that ele- ment will be the null list. For example: select {file3 file4 file5} {file6 file7} {} 10.5 could return {file3 file4} {file6} {} or perhaps file3 {} {} FFIILLEE SSCCAANNNNIINNGG CCOOMMMMAANNDDSS These commands provide a facility to scan files, matching lines of the file against regular expressions and executing Tcl code on a match. With this facility you can use Tcl to do the sort of file processing that are traditionally done with aawwkk. And since Tcl's approach is more declarative, some of the scripts that are really hard to write in awk are a snap in Tcl. File scanning in Tcl centers around the concept of a _s_c_a_n _c_o_n_t_e_x_t. A scan context contains one or more match state- ments, which associate regular expressions to scan for with Tcl code to be executed when the expressions are matched. ssccaannccoonntteexxtt [[_o_p_t_i_o_n] This command manages file scan contexts. A scan con- text is a collection of regular expressions and com- mands to execute when that regular expression matches a line of the file. A context may also have a single default match, to be applied against lines that do not match any of the regular expressions. Multiple scan contexts may be defined and the may be reused on multi- ple files. A scan context is identified by a context handle. The ssccaannccoonntteexxtt command takes the following Tcl 12 TclX UNKNOWN MANUAL SECTION TclX forms: ssccaannccoonntteexxtt ccrreeaattee Create a new scan context. The ssccaannmmaattcchh command is used to define patterns in the context. ssccaannccoonntteexxtt ddeelleettee _c_o_n_t_e_x_t_h_a_n_d_l_e Delete the scan context identified by _c_o_n_t_e_x_t_h_a_n_d_l_e and free all the match statements and compiled regular expressions associated with the specified context. ssccaannffiillee _c_o_n_t_e_x_t_h_a_n_d_l_e _f_i_l_e_h_a_n_d_l_e Scan the file specified by _f_i_l_e_h_a_n_d_l_e, starting at the current file position. Check all patterns in the scan context specified by _c_o_n_t_e_x_t_h_a_n_d_l_e against it, execut- ing the match commands corresponding to patterns matched. ssccaannmmaattcchh [[--nnooccaassee] _c_o_n_t_e_x_t_h_a_n_d_l_e [_r_e_g_e_x_p] _c_o_m_m_a_n_d_s Specify Tcl _c_o_m_m_a_n_d_s, to be evaluated when _r_e_g_e_x_p is matched by a ssccaannffiillee command. The match is added to the scan context specified by _c_o_n_t_e_x_t_h_a_n_d_l_e. Several match statements may be specified for a give context. _R_e_g_e_x_p is a regular expression (see the rreeggeexxpp com- mand). If --nnooccaassee is specified as the first argument, the pattern is matched regardless of alphabetic case. If _r_e_g_e_x_p is not specified, then a default match is specified for the scan context. The default match will be executed when a line of the file does not match any of the specified regular expressions. The array, mmaattcchhIInnffoo, is available when the Tcl code is executed and contains information about the file being scanned. It is local to the top level of the match command unless declared global at that level. If it is to be used as a global it _m_u_s_t be declared global before ssccaannffiillee is called (since ssccaannffiillee sets the mmaattcchhIInnffoo before the match code is executed, a subse- quent gglloobbaall will override the local variable). The text of the file line that was matched is in mmaattcchhIInnffoo((lliinnee)). The byte offset into the file of the line that was matched is in mmaattcchhIInnffoo((ooffffsseett)). The line number of the line that was matched is in mmaattcchhIInnffoo((lliinneennuumm)). This is relative to the first line scanned, not the first line of the file. The first line is line number one. The file handle of the file being scanned is in mmaattcchhIInnffoo((hhaannddllee)). All ssccaannmmaattcchh patterns that match a line will be processed in the order that the specifications were added to the scan context. The remainder of the ssccaannmmaattcchh pattern-command Tcl 13 TclX UNKNOWN MANUAL SECTION TclX pairs may be skipped for a file line if a ccoonnttiinnuuee is exe- cuted in the match command. If a rreettuurrnn is executed in the body of the match command, the ssccaannffiillee command in progress returns with the value passed to rreettuurrnn as it's value. MMAATTHH CCOOMMMMAANNDDSS These commands make many additonal math functions available in Tcl, including min, max, trig functions, exponent, loga- rithm, square root, and more. An integer random number gen- erator is provided as well. aaccooss _n_u_m Returns the arccosine of _n_u_m. _n_u_m is in radians. aassiinn _n_u_m Returns the arcsin of _n_u_m. _n_u_m is in radians. aattaann _n_u_m Returns the arctangent of _n_u_m. _n_u_m is in radians. cceeiill _n_u_m Returns the smallest integer not less than _n_u_m (float- ing point). ccooss _n_u_m Returns the cosine of _n_u_m. _n_u_m is in radians. ccoosshh _n_u_m Returns the hyperbolic cosine of _n_u_m. eexxpp _n_u_m Returns _e to the power of _n_u_m. ffaabbss _n_u_m Returns the absolute value of _n_u_m (floating point). fflloooorr _n_u_m Returns the largest integer not greater than _n_u_m (floating point). ffmmoodd _n_u_m_1 _n_u_m_2 Returns _n_u_m_1 modulo _n_u_m_2. mmaaxx _n_u_m_1 _n_u_m_2 [.._n_u_m_N] Returns the argument that has the highest numeric value. The arguments, _n_u_m_N may be any interger or floating point values. mmiinn _n_u_m_1 _n_u_m_2 [.._n_u_m_N] Returns the argument that has the lowest numeric value. The arguments, _n_u_m_N may be any interger or floating point values. Tcl 14 TclX UNKNOWN MANUAL SECTION TclX lloogg _n_u_m Returns the natural logarithm of _n_u_m. lloogg1100 _n_u_m Returns the logarithm base 10 of _n_u_m. ppooww _n_u_m_1 _n_u_m_2 Returns _n_u_m_1 to the power of _n_u_m_2. rraannddoomm lliimmiitt | sseeeedd [_s_e_e_d_v_a_l] Generate a pseudorandom integer number greater than or equal to zero and less than _l_i_m_i_t. If sseeeedd is speci- fied, then the command resets the random number genera- tor to a starting point derived from the sseeeeddvvaall. This allows one to reproduce a random number sequence for testing purposes. If _s_e_e_d_v_a_l is omitted, then the seed is set to a value based on current system state and the current time, providing a reasonably interesting and ever-changing seed. ssiinn _n_u_m Returns the sin of _n_u_m. _n_u_m is in radians. ttaann _n_u_m Returns the tangent of _n_u_m. _n_u_m is in radians. ssiinnhh _n_u_m Returns the hyperbolic sin of _n_u_m. ssqqrrtt _n_u_m Returns the square root of _n_u_m. ttaannhh _n_u_m Returns the hyperbolic tangent of _n_u_m. LLIISSTT MMAANNIINNIIPPUULLAATTIIOONN CCOOMMMMAANNDDSS Extended Tcl provides two additional list manipulation com- mands. lleemmppttyy _l_i_s_t Determine if the specified list is empty. If empty, 1 is returned, otherwise, 0 is returned. This command is an alternative to comparing a list to an empty string. llvvaarrppoopp _v_a_r [_i_n_d_e_x [_s_t_r_i_n_g]] The llvvaarrppoopp command pops (deletes) the element indexed by _i_n_d_e_x from the list in the variable _v_a_r. If _i_n_d_e_x is omitted, then 0 is assumed. If _s_t_r_i_n_g, is speci- fied, then the deleted element is replaced by _s_t_r_i_n_g. The replaced or deleted element is returned. Thus ``lvarpop argv 0'' returns the first element and sets argv to contain the remainder of the string. Tcl 15 TclX UNKNOWN MANUAL SECTION TclX KKEEYYEEDD LLIISSTTSS Extended Tcl defines a special type of list referred to as _k_e_y_e_d _l_i_s_t_s. These lists provided a structured data type built upon standard Tcl lists. This provides a functional- ity similar to ssttrruucctts in the C programming language. A keyed list is a list in which each element is a key and value pair field. These elements are actually lists them- selves, were the key is the first element of the list, and the value is the second. The key-value pairs are refered to as _f_i_e_l_d_s. This is an example of a keyed list: {{NAME {Frank Zappa}} {JOB {musician and composer}} By convention, `.' is a field name separator, allowing nest- ing of fields, even though keyed list are only one level deep. Currently none of the commands explictly function on nested field names, but they may in a future release, so `.' should not be used for other than a field separator in a name. For example: {{ID 106} {NAME.FIRST Frank} {NAME.LAST Zappa}} All key list functions take the name of the variable con- taining the keyed list as an argument (i.e. passed by refer- ence) rather than the value. kkeeyyllddeell _l_i_s_t_v_a_r _k_e_y Delete the field specified by _k_e_y from the keyed list in the variable _l_i_s_t_v_a_r. This removes both the key and the value from the keyed list. kkeeyyllggeett _l_i_s_t_v_a_r _k_e_y [_r_e_t_v_a_r | {}] Return the value associated with the _k_e_y out of keyed list in the variable _l_i_s_t_v_a_r. If _r_e_t_v_a_r is not speci- fied, then the value will be returned as the result of the command. If _k_e_y is not found in the list, an error will result. If _r_e_t_v_a_r is specified and _k_e_y is in the list, then the value is returned in the variable _r_e_t_v_a_r and the command returns one. If _k_e_y is not in the list, the command will return 00 and _r_e_t_v_a_r will be unchanged. If {{}} is specified for _r_e_t_v_a_r, the value is not returned, only the presence of the key is determined. kkeeyyllsseett _l_i_s_t_v_a_r _k_e_y _v_a_l_u_e Set the value associated with the _k_e_y in the keyed list in the variable _l_i_s_t_v_a_r to _v_a_l_u_e. If listvar does not exists, it is created. If _k_e_y is not currently in the list, it will be added. If it already exists, _v_a_l_u_e overrides the existing value. SSTTRRIINNGG AANNDD CCHHAARRAACCTTEERR MMAANNIIPPUULLAATTIIOONN CCOOMMMMAANNDDSS The commands provide additional functionality to classify Tcl 16 TclX UNKNOWN MANUAL SECTION TclX characters, convert characters between character and numeric values, and index into a string, determine the length of a string, extract a range of character from a string, repli- cate a string a number of times, and transliterate a string (similar to the _t_r command). cciinnddeexx _s_t_r_i_n_g _i_n_d_e_x Returns the character indexed by _i_n_d_e_x (zero based) from _s_t_r_i_n_g. This command is a shortcut for: ssttrriinngg iinnddeexx _s_t_r_i_n_g _i_n_d_e_x cclleennggtthh _s_t_r_i_n_g Returns the length of _s_t_r_i_n_g in characters. This com- mand is a shortcut for: ssttrriinngg lleennggtthh _s_t_r_i_n_g ccrraannggee _s_t_r_i_n_g _f_i_r_s_t _l_a_s_t Returns a range of characters from _s_t_r_i_n_g starting at _f_i_r_s_t (zero-based) until _l_a_s_t. The special keyword eenndd may be specified for _l_a_s_t to indicate that the remainder of the string is to be extracted. This com- mand is a short cut for: ssttrriinngg rraannggee _s_t_r_i_n_g _f_i_r_s_t _l_a_s_t ccssuubbssttrr _s_t_r_i_n_g _f_i_r_s_t _l_e_n_g_t_h Returns a range of characters from _s_t_r_i_n_g starting at _f_i_r_s_t (zero-based) for _l_e_n_g_t_h characters. The special keyword eenndd may be specified for _l_e_n_g_t_h to indicate that the remainder of the string is to be extracted. This command is a short cut for: ssttrriinngg rraannggee _s_t_r_i_n_g _f_i_r_s_t [eexxpprr _l_e_n_g_t_h--11] ccttyyppee _c_l_a_s_s _s_t_r_i_n_g Determine if all characters in _s_t_r_i_n_g are in of the specified _c_l_a_s_s. Returns 11 if they are all of _c_l_a_s_s and 00 if they are not or if the string is null. This command also provides another method (besides ffoorrmmaatt and ssccaann) of converting between an ASCII character and its numeric value. The following ccttyyppee commands are available. ccttyyppee aallnnuumm _s_t_r_i_n_g Tests that all characters are alphabetic or numeric characters as defined by the character set. ccttyyppee aallpphhaa _s_t_r_i_n_g Tests that all characters are alphabetic charac- ters as defined by the character set. ccttyyppee aasscciiii _s_t_r_i_n_g Tests that all characters are an ASCII character Tcl 17 TclX UNKNOWN MANUAL SECTION TclX (a non-negative number less than 0200). ccttyyppee cchhaarr _n_u_m_b_e_r Converts the numeric value, _s_t_r_i_n_g, to an ASCII character. Number must be in the range 0 through 255. ccttyyppee ccnnttrrll _s_t_r_i_n_g Tests that all characters are ``control charac- ters'' as defined by the character set. ccttyyppee ddiiggiitt _s_t_r_i_n_g Tests that all characters are valid decimal digits, i.e. 0 through 9. ccttyyppee ggrraapphh _s_t_r_i_n_g Tests that all characters within are any character for which _c_t_y_p_e _p_r_i_n_t is true, except for space characters. ccttyyppee lloowweerr _s_t_r_i_n_g Tests that all characters are lowercase letters as defined by the character set. ccttyyppee oorrdd _c_h_a_r_a_c_t_e_r Convert a character into its decimal numeric value. The string must be one character long. ccttyyppee ssppaaccee _s_t_r_i_n_g Tests that all characters are either a space, horizontal-tab, carriage return, newline, vertical-tab, or form-feed. ccttyyppee pprriinntt _s_t_r_i_n_g Tests that all characters are a space or any char- acter for which _c_t_y_p_e _a_l_n_u_m or _c_t_y_p_e _p_u_n_c_t is true or other ``printing character'' as defined by the character set. ccttyyppee ppuunncctt _s_t_r_i_n_g Tests that all characters are made up of any of the characters other than the ones for which aallnnuumm, ccnnttrrll, or ssppaaccee is true. ccttyyppee uuppppeerr _s_t_r_i_n_g Tests that all characters are uppercase letters as defined by the character set. ccttyyppee xxddiiggiitt _s_t_r_i_n_g Tests that all characters are valid hexadecimal digits, that is _0 through _9, a through _f or _A through _F. Tcl 18 TclX UNKNOWN MANUAL SECTION TclX rreepplliiccaattee _s_t_r_i_n_g _c_o_u_n_t Returns _s_t_r_i_n_g replicated _c_o_u_n_t times. ttrraannsslliitt _i_n_r_a_n_g_e _o_u_t_r_a_n_g_e _s_t_r_i_n_g Translate characters in _s_t_r_i_n_g matching characters in _i_n_r_a_n_g_e to the corresponding character in _o_u_t_r_a_n_g_e. _I_n_r_a_n_g_e and _o_u_t_r_a_n_g_e may be list of characters or a range in the form `A-M'. Example: translit a-z A-Z foobar returns FOOBAR Tcl 19